BCI NET

home *** CD-ROM | disk | FTP | other *** search

/ BCI NET / BCI NET Dec 94.iso / archives / applications / misc / pcal-4.5.lha / pcal / Pcal.hlp < prev next >

Wrap

Text File | 1994-10-16 | 31.4 KB | 708 lines

1 PCAL Pcal generates PostScript to produce landscape or portrait calendars for any month and year. The arguments month,year, and nmonths, if provided, should be numeric. The month value should be in the range 1 - 12, and the year value should be specified as 1 or 2 digits or as the full 4 digit year. If no numeric arguments are provided, the calendar for the current month and year will be generated. If one numeric argument is provided, it is interpreted as the year value, and calendars for the entire year will be generated. Otherwise, nmonths months, starting with month and year, will be generated. For whole-year calendars (i.e. the -w option is given), the command line arguments are interpreted somewhat differently. By default, all months in the current year are printed, starting with January. If the month argument alone is given, it is expected to be the desired year to print, and prints all of the months in the given year. If both month and year are given, then 12 consecutive months are printed starting at the given month and year. If the month, year, and nmonths arguments are all present, printing begins with the given month and year and nmonths months are printed, rounded up to the nearest multiple of 12. VMS Version Execution format: pcal [options] [mm yy] [n] 2 Parameters mm yy n "mm" and "yy" are numeric values of the month (1-12) and year (0-99) (i.e., July 1990 would be 7 90). If you just include the "yy" option, an entire 12 months of calendars will be generated. A specific month can be produced by including the "mm" parameter. The "n" parameter will produce the "n" consecutive months of calendars starting with the requested month. The following flags may be specified (in increasing order of precedence) in global symbol PCAL_OPTS, in "opt" lines in the date file (all but -c, -e, -f, -h, -u, -v, -"D", -"U"), or on the command line. Any flag which normally takes an argument may be specified without the argument; this resets its value to the program default. (-"D" alone thus clears all defined symbols; -"U" alone has no effect.) The "-" flag has been added to disambiguate cases where an argument-less flag has been specified immediately before a numeric parameter: pcal -t - 9 90 2 Options Pcal accepts several command line options (or from the CALENDAR.DAT file). The uppercase options should be enclosed in quotes as pcal is case-sensitive and the VMS command line parser will convert the string to upper case otherwise. The quoted strings are not needed if the options are included within the CALENDAR.DAT file. 3 -e Print an empty calendar (i.e., do not print entries from a CALENDAR.DAT file.) 3 -f <FILE> Directs pcal to use the file name <FILE> as the input file in place of the default CALENDAR.DAT file. Note that the search rules are different when -f is used. If <FILE> is an absolute file name, then pcal attempts to open only that file. Otherwise, pcal looks for <FILE> in the current directory, then in the directory indicated by the environment variable PCAL_DIR (if defined), and finally in the directory where the pcal executable resides. If the given <FILE> file is not found, an error results. 3 -o <FILE> Directs pcal to write the PostScript calendar into FILE (default: CALENDAR.PS in the current directory.) 3 -l This will cause the output to come out in landscape mode (This is the default). This also resets the x- and y-axis scaling and translation factors to the defaults for landscape mode. 3 -p This will cause the output to come out in portrait mode instead of landscape mode. This also resets the x- and y-axis scaling and translation factors to the defaults for portrait mode. 3 -j Directs pcal to print the Julian (Day Of Year, DOY) in each calendar box. 3 -"J" Directs pcal to print the Julian (Day Of Year, DOY) and the number of days remaining in the year in each calendar box. 3 -m This option causes a moon to be printed on days corresponding to a full, half, or new moon (default: no moons). 3 -"M" This option causes a fractional moon to be printed on all days (default: no moons). 3 -g day1[-day2] | all | holiday Causes all dates falling on weekday day1 (through day2 if specified) to be printed in gray; -g all causes all weekdays (other than holidays) to be printed in gray; -g holiday causes all holidays to be printed in gray. day1 and day2 may wrap around weekends; for example, -g fri-sun causes Fridays, Saturdays, and Sundays to be printed in gray. 3 -"O" Causes "gray" dates to be printed as outlined characters. 3 -"G" day1[-day2] | all | holiday Similar to -g, but the selected days will be printed as outlined characters filled with gray. Note: The default for the above options is to print Saturdays, Sundays, and holidays in gray and all other days in black. For backward compatibility with earlier versions of pcal, -"O" and -"G" alone change all non-black days to the specified color. 3 -b day1[-day2] | all | holiday Similar to - you guessed it - -g, but the selected days will be printed in black. Since black is the default for weekdays, -b is primarily used to overriding other flags (e.g., -g all -b sat-sun ). 3 -s <date_shade>[/fill_shade] Overrides the default values for date and/or fill box shading. These values must be in the range 0.0 (black) through 1.0 (white); they may be set independently of each other. The default values are 0.8 for dates and 0.9 for empty boxes. Note: For use with color printers, date_shade and fill_shade may optionally be specified as a set of red:green:blue values; red, blue, and green must in the range 0.0 through 1.0. At least one ':' must be present for this option to be recognized; omitted values are set to 0.0. 3 -"F" <DAY> Selects weekday DAY as the first day of the week. The given day will appear in the left-most column of the calendar. 3 -"A" Directs pcal to use American date conventions "mm/dd[/yy]" and "month dd" when parsing the date file (default). 3 -"E" Directs pcal to use European date conventions "dd/mm[/yy]" and "dd month" when parsing the date file. 3 -"X" xtrans Specifies the x-axis translation value for positioning the output on the page. 3 -"Y" ytrans Specifies the y-axis translation value for positioning the output on the page. 3 -x xscale Specifies the x-axis scaling factor for the calendar size. 3 -y yscale Specifies the y-axis scaling factor for the calendar size. 3 -t <title_font>[/size] Specifies the name of a font to use to print all the calendar heading text: the month name and year at the top of the calendar, the weekday names, the notes box heading, and the foot strings. The user may optionally specify the font size for the month/year heading (single-month calendar only); for example, pcal -t Times-Roman/54 sets the font to Times-Roman and the month/year point size to 54. The font size may also be changed independently: pcal -t /54 changes the point size to 54 without affecting the font name. 3 -d <date_font>[/size] Similar to the -t option, but selects the font and/or size used to print the dates. 3 -n <text_font>[/size] Similar to the -t and -d options, but selects the font and/or size used to print the text associated with each day and in the "Notes" blocks. 3 -r <mapping> Specifies an 8-bit character set remapping for printing the diacritical marks common to European languages; mapping may be "Roman8" (ROMAN-8 extended character set), "Latin1" (ISO LATIN-1 extended character set), or "none" (builtin 8-bit mappings only). It may be abbreviated to a single character if desired. 3 -"D" <SYMBOL> Defines the named SYMBOL prior to reading the date file. 3 -"U" <SYMBOL> Un-Defines the named SYMBOL prior to reading the date file. 3 -"L" <STRING> Causes the accompanying string to be printed as a left-justified footer. Format specifiers denoting the month and/or year may appear in the string; the appropriate values will be substituted upon printing. 3 -"C" <STRING> Similar to -"L", but causes the accompanying string to be printed as a centered footer. 3 -"R" <STRING> Similar to -"L", but causes the accompanying string to be printed as a right-justified footer. 3 -"N" <STRING> Caused the accompanying string to be printed as the heading for the "Notes" box. Note however, that pcal makes no attempt to ensure that it fits. 3 -"B" Causes pcal to leave unused calendar boxes blank (default is gray). 3 -# n Causes pcal to print n copies (maximum: 100) of each output page. 3 -"S" Causes pcal to suppress printing the small calendars. See the CAVEATS section for further details. 3 -k Causes pcal to print the small calendars in the upper left corner (the default is to print them at the lower right). 3 -"K" Causes pcal to print the small calendar for the previous month in the upper left corner and the next month in the lower right (the default is to print both at the lower right). 3 -w Causes pcal to print a calendar for 12 consecutive months: 3 rows / 4 columns in landscape mode, 4 rows / 3 columns in portrait mode. See the CAVEATS section for details on the use of this option with other options. 3 -c Causes pcal to generate a date file suitable for use as input to the Un*x "calendar(1)" utility. The normal PostScript output is suppressed. 3 -z <time_zone> Forces pcal to ignore the moon file and to use its internal algorithm for moon phase calculations, adjusting the phase by time_zone hours (where time_zone is expressed in hours west of UTC). 3 -"I" Resets all parameters to the program defaults. 3 -h Causes pcal to write version information, parameter usage message, and full explanation of options and file formats (to stdout) and terminate. 3 -u Causes pcal to write version information and parameter usage message (to stdout) and terminate. 3 -v This prints version information only. 2 Date_File By default, pcal simply prints an empty calendar. Its real power is in its ability to place "events" in appropriate days on the calendar, thus allowing the user to create personalized calendars. This is achieved through the use of the "date file". The date file is named CALENDAR.DAT. Pcal will look in several places for such a file. First, if the environment variable PCAL_DIR is defined, pcal searches the directory indicated by that variable. Next, pcal searches the user's home directory (as specified by the HOME environment variable). If neither PCAL_DIR nor HOME is defined, pcal searches the current directory instead. Finally, the directory where the pcal executable resides will be checked. If no date file is found, an empty calendar is printed; no error is generated. If a date file is found, it will be searched for lines with leading dates matching the requested month and year. Any text following the dates found will be printed on the calendar under the appropriate day of the month. Dates in the CALENDAR.DAT file may be expressed in any of several formats: <ordinal> <day_spec> in <month_spec>[*] [<text>] [<ordinal>] <day_spec> <prep> <date_spec>[*] [<text>] <date_spec>[*] [<text>] <holiday> Where: <month_name> := first 3+ characters of name of month, or "all" <month_spec> := <month_name>, or "year" <day_spec> := first 3+ characters of name of weekday, "day", "weekday", "workday", "holiday", "nonweekday", "nonworkday", "nonholiday", "new_moon", "first_quarter", "full_moon", or "last_quarter" <ordinal> := any ordinal number "first", "1st", ... "fifth", "5th", "last", "odd", "even", or "all" <prep> := "before", "preceding", "after", "following", "on_or_before" ("oob"), or "on_or_after" ("ooa") <holiday> := "Christmas", "Thanksgiving", etc. <sep> := 1 or more non-numeric, non-space, non-"*" characters <month> := day of month (1-31) <day> := a numeric month (1-12) <year> := a numeric year If the -"A" option (American date formats, the default) is given: <date_spec> := <month_name><day> | <month><sep><day>[<sep><year>] If the -"E" option (European date formats) is given: <date_spec> := <day><month_name> | <day><sep><month>[<sep><year>] 3 Text_Format_Description Pcal also allows format specifiers in both the text and foot strings (see the -L, -C, -R, and -N options below); each will be replaced by a corresponding string as outlined in the table below. Most of these are derived from the ANSI C strftime() function; the %[louwMD] and %[o0+\-] format specifiers are specific to pcal: %a abbreviated weekday %A full weekday %b abbreviated month name %B full month name %d day of month (1-31) %j day of year (1-366) %l days left in year (0-365) %m month (1-12) %U week number (0-53) %W week number (0-53) %u week number (1-54) %w week number (1-54) %y year w/o century (00-99) %Y year w/century %% % character %o print number as ordinal %0 print number with leading zeroes %+ use following month or year %- use previous month or year %{+N}[DWMY] adjust date by +N days/weeks/months/years %{\-N}[DWMY] adjust date by \-N days/weeks/months/years %u specifier considers the week containing 1/1 as week 1 and the following logical Sunday (the first day of the week as printed; cf. the \-F option below) as the start of week 2; %U considers the first logical Sunday as the first day of week 1. %w and %W behave like %u and %U respectively, but use the first logical Monday instead. Note that %w has a different meaning to strftime(). The %o format specifier prints a number as an ordinal, with the appropriate suffix ("st", "nd", "rd", or "th" in English) appended; for example, %od prints the day of the month as "1st", "2nd", "3rd", etc. Unlike strftime(), pcal defaults to printing numbers (except %y ) without leading zeroes. If leading zeroes are desired, the `0' prefix may be used. For example, %0j prints the first day of year as "001". The %+ and %\- format specifiers direct pcal to substitute the following/previous month/year in the following [bBmyY] specifier. For example, %+B prints the name of the next month. The %{[+\-]N}[DWMY] format specifiers do not print anything, but instead adjust the working date by \(+- N days ( D ), weeks ( W ), months ( M ), or years ( Y ). Subsequent format specifiers use the adjusted date instead of the current date. For example, %+1M %B %Y adjusts the date forward by one month and then prints the resulting month and year ("January 1992" in December, 1991); %\-2W %b %d adjusts the date backward by two weeks and prints the resulting month and day ("Jul 26" on August 9). Such date adjustments are normally cumulative; for example, %+1Y%\-1D adjusts the date forward by one year and then backward by one day. If %D or %M is specified alone (or if N is zero), pcal restores the original date. Note that %M has a different meaning to the strftime() function. The "Notes" box (see below) uses the first of the current month as the default date. All foot strings use the first of the current month in single-month mode and the first of the starting month in whole-year mode. 3 Date_Syntax_Description Any non-numeric character may separate numeric dates. Holidays may be flagged by following the date immediately with "*" as in the examples above; this will cause the date to be printed in gray. "Each" and "every" are accepted as synonyms for "all", and any word may be used in place of "in". The abbreviations "oob" and "ooa" may be used in place of the keywords "on_or_before" and "on_or_after", respectively. "Nearest" attempts to match the specified date; if that fails, it tries the day after, then the day before, then two days after, two days before, and so forth until a match occurs. Wildcard day names are also provided. The keyword "weekday" applies to any days which are normally printed in black on the calendar. The keyword "workday" is the same, but does not include any holidays. The keyword "holiday" includes only those days flagged as holidays. The keywords "nonweekday", "nonworkday", and "nonholiday" are also recognized as negations of the above. See the Caveats below for important notes on using these keywords. Moon phases may also appear as wildcards; "nm" is accepted as a synonym for "new_moon", "1q" and "fq" for "first_quarter", "fm"' for "full_moon", "3q" for "third_quarter", and "lq" for "last_quarter". Ordinal day numbers may be used to specify dates, either relative to the month or to the year. Either words or numeric abbreviations may be used for "first" through "fifth"; higher numbers must be given using the numeric equivalent (e.g. 100th). Negative ordinal numbers may even be used. For example, "-2nd" means "next to last". "Odd" and "even" do not refer to the actual date; instead, "odd" means "alternate, starting with the first", and "even" means "alternate, starting with the second". Thus, "odd Fridays in March" refers to the first, third, and (if present) fifth Fridays in March - not to those Fridays falling on odd dates. "All" refers to each individual month; "year" refers to the year as an entity. Thus "odd Fridays in all" refers to the first, third, and fifth Friday of each month, while "odd Fridays in year" refers to the first Friday of January and every other Friday thereafter. Text in the date file may use C-like escape sequences (i.e. a "\" followed by a character, 1--3 octal digits, or "x" followed by 1--2 hexadecimal digits). Escaped whitespace (including newline) and the standard ANSI character escapes ("\a", "\b", "\f", "\n", "\r", "\t", "\v") are all replaced by a single blank. Lines in the CALENDAR.DAT file consisting of year #### (where #### is a numeric year) can be used to set the year for following entries. This assumes that the following entries do not contain a year; any date entries containing year information will set the remembered year to that year. Lines in the CALENDAR.DAT file consisting of opt <options> can be used to override the defaults for any command-line options except -e, -f, -h, -"D", and -"U". Any options specified in this manner are, in turn, overridden by those specified explicitly on the command line. Note that the upper case letter options do NOT need to be enclosed in quotes if they are put in the CALENDAR.DAT file. Enclose the upper case letters in quotes only when they are used on the DCL. Lines in the CALENDAR.DAT file consisting of note [/<number>] <month> can be used to place notes regarding the entire month is one of the unused blocks of the calendar. The <month> indicator may be either a number 1 through 12 or an alphabetic month name as described above; "note all" will place the associated text in the notes block for each month in the current year. <number> is an optional positive or negative number specifying the empty box where the associated text is to be placed. If positive, pcal counts forward from the first empty box; if negative, pcal counts backward from the last empty box. Thus, "note/1" places the associated text in the first empty box; "note/-3" in the third-to-last. The default is -1 if no <number> is given (last empty box, immediately preceding the small calendars on the bottom row; cf. \-S , \-k , and \-K , below). Comments are supported in the CALENDAR.DAT file. Any characters following a "#" character through the end of the line are ignored (unless the `#' character is escaped by `\'). Pcal supports rudimentary cpp-like functionality in the date file, allowing the following constructs: define | undef, if{{n}def} ... elif ... * else ... endif, and include. Note that these are not preceded by "#" as they are in C. Symbol names defined using these keywords (or via the -"D" option) are case-insensitive. It is not an error to undef an undefined symbol, nor to define a previously-defined one. An ifdef alone is always false; an ifndef alone is always true. if is accepted as an synonym for ifdef. The name of the file in the include directive may optionally be surrounded by either "" or <>, both of which are ignored. If the name is not an absolute path, it is taken to be relative to the directory where the file containing the directive is located. pcal normally terminates immediately if the file specified in an include directive does not exist. An alternate form of the directive, include?, directs pcal to continue silently if the file does not exist or cannot be opened. In addition to pre-processing keywords, pcal also accepts boolean expressions in if{{n}}def} and elif directives. These expressions consist of symbol names joined by the boolean operators !, &, ^, and |, in order of precedence, high to low. Parentheses may be used to alter the precedence. The synonyms && and || are accepted for & and |. A symbol name evaluates to true if currently defined, false if not; thus: ifdef A | B | C ... is true if any of the symbols A, B, and C is defined, and: ifdef A & B & C ...is true if they all are. Note that ifndef <expr> is equivalent to ifdef !( <expr> ). 3 Example Date File Example: # A sample "opt" line to change the fonts and output file names, # to print only Sundays in gray, and to print moons on all days: # opt -d Helvetica-Bold -t Helvetica-Bold -o myfile.ps -b all -g sun -M year 1994 # set year explicitly 1/1* New Year's Day ifndef Arizona 3rd Mon in Jan* Martin Luther King's Birthday endif 2/2 Groundhog Day Feb 14 Valentine's Day 3rd Monday in Feb* Presidents' Day 3/17 St. Patrick's Day last Monday in May* Memorial Day 7/4* Independence Day 1st Monday in Sep* Labor Day second Monday in Oct* Columbus Day (observed) first workday in all %-B progress report due all Fridays in Oct Status Meeting, 11 AM all Fri in all Time card due, 3 PM all Monday in all Fiscal week %0W -2nd workday in all Schedule for %+B due %+2D 2nd full_moon in all Blue Moon Fri on_or_before all 15 Pay Day even Fridays in year Pay Day 183rd day of year Mid-year (%l days left) 10/12 Columbus Day (traditional) 10/31 Halloween Tue after first Mon in Nov Election Day 11/11* Veterans' Day fourth Thu in Nov* Thanksgiving Fri after 4th Thu in Nov* Day after Thanksgiving day after fourth Thu in Nov* 12/25/94* Christmas # American 12/24* Christmas Eve 12/25* Christmas 25.12.94* Christmas # European 25. 12.* Christmas # European 25 Dec* Christmas # European 25. Dec* Christmas # European workday nearest 12/25* Holiday last day in Dec* New Year's Eve last workday in all Status reports due note Dec Office closed throughout week of Christmas 1/1/95* New Year's Day # set new year implicitly 2 Moon_File If a file of the name MOON##.DAT (where ## is the last two digits of the calendar year) exists in the same directory as the date file (or in the directory where pcal resides) pcal uses the information contained within to calculate the phase of the moon. If no such file exists, pcal uses an extremely reliable algorithm. This is the preferred method of use. Entries in the moon file must conform to the following syntax: If the -"A" option (American date formats, the default) is given: <quarter> <month><sep><day> [<hour><sep><min>] If the -"E" option (European date formats) is given: <quarter> <day><sep><month> [<hour><sep><min>] Where: <quarter> := "nm", "fq" or "1q", "fm", "3q" or "lq" (new moon,first quarter,full moon,last quarter) <hour> := number 0-23 (24-hour clock) <min> := number 0-59 This file must contain entries for all quarter moons in the year, in chronological order; if any errors are encountered, pcal will revert to using its default algorithm. As in the date file, comments start with "#" and run through end-of-line. The moon file may optionally contain an opt -A or opt -E line to specify the format of its own date entries independently of the format used in the date file. No other flags are legal in the moon file. 3 Example The following is a short example of an European style (-"E) moon data file. It is taken from the MOON91.DAT file supplied with pcal. 3q 01/07 13:37 # third quarter nm 01/15 18:51 # new moon 1q 01/23 09:23 # first quarter fm 01/30 01:10 # full moon 2 Logical_Names Pcal optionally uses two (2) logical names during execution. A user may define them or let the administrator set them up. 3 Pcal_Dir Pcal logical name for the location of the directory for input and output files. In this way, a user can over-ride the current default location for the source of the CALENDAR.DAT input file and the CALENDAR.PS output file. 3 Pcal_Opts Pcal also looks for a logical name "Pcal_Opts; if defined, its contents are parsed as command-line flags. These over-ride the program defaults, but are over-ridden by any specified via "opt" lines in the date file or on the command line. Example: Define Pcal_Opts "-n Helvetica -D meetings" ! login.com pcal -"U" meetings 9 90 ! un-define symbol at runtime 2 Caveats The "workday" and "holiday" keywords are aware of only those holidays which have already been flagged at the point where they appear. For example, consider January 1990: January 1990 S M Tu W Th F S 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 If the CALENDAR.DAT file looked like this: workday on_or_before all 15 payday 3rd Mon in Jan* MLK day then Pcal would mark the 15th as "payday" since at that point in the CALENDAR.DAT file it has no way of knowing that January 15th will later be flagged as a holiday. If the two lines were reversed, such that the holiday preceded the "workday" wildcard, then Pcal would work as intended, marking instead the 12th as "payday". Also, beware of year boundaries which affect the handling of all of the day wildcard keywords. In general, it is best to place monthly wildcards such as the example above at the end of each year to achieve the desired effect. Only the positive ordinals may be used in conjunction with prepositions (e.g., "fourth Sunday before 12/25"). (It could be argued that "last Sunday before 12/25" should be accepted as a synonym for "first Sunday before 12/25", but then what does "last Sunday after 12/25" mean?) When the -w and -p options are used together, pcal revises the y-scale factor in order to use the entire portrait page; therefore, the user should avoid using use the -y using both the -w and -p options. Use of the -w option in any case effectively disables the -m, -"M", -j, and -"J" options. The output of the -c option may be used as input to subsequent runs of pcal. Note, however, that opt lines (except for an automatic "opt \-[A|E]" ), comments, "note" text, and ifdef'd-out source will be lost. The -S option interacts with note[/<number>]; if used, it should be specified either on the command line or prior to the first note line in the date file. 2 Authors The original PostScript code to generate the calendars was written by Patrick Wood (Copyright (c) 1987 by Patrick Wood of Pipeline Associates, Inc.), and authorized for modifica- tion and redistribution. The calendar file inclusion code was originally written in bs(1) by Bill Vogel of AT&T. Patrick's original PostScript was modified and enhanced several times by others whose names have regrettably been lost. Ken Keirnan of Pacific Bell assembled the original "C" version upon which this is based; additional modifications and enhancements are the work of Joseph P. Larson, Ed Hand, Andrew W. Rogers, Mark Kantrowitz, Joe Brownlee, Jamie Zawinski, Richard L. Dyson, Bill Hogsett, Floyd Miller, Andy Fyfe, and Geoff Kuenning. 2 Version This help file currently reflects pcal v4.5 dated 6-OCT-1994 and was updated by Richard Dyson.